Fix stale cache-hit lifecycle claims in middleware doc comments - #915

Linked issue

Refs prisma/web#8008 (Prisma Next docs validation, which surfaced these stale comments). Stacked on #912 (examples/extensions-middleware-docs) — the corrected comments reference its slowQueryWarning example, so that PR must merge first. Sibling fix from the same validation pass: #913.

At a glance

// examples/prisma-next-demo/src/prisma/db.ts
middleware: [
  // Cache first: interceptors are consulted in registration order and
  // the first non-`undefined` result wins, so the cache gets first
  // claim. A hit skips only the driver call and per-row `onRow` hooks:
  // every middleware's `beforeExecute` (`lints`, `budgets`) has already
  // run before any `intercept` is consulted, and `afterExecute` still
  // fires for all of them with `source: 'middleware'`. The cache stores
  // raw rows; the runtime still runs `decodeRow` on the hit path, so
  // consumers see decoded values in both cases.
  createCacheMiddleware({ maxEntries: 1_000 }),
  lints(),
  budgets({
    maxRows: 10_000,
    defaultTableRows: 10_000,
    tableRows: { user: 10_000, post: 10_000 },
    maxLatencyMs: 1_000,
  }),
  slowQueryWarning({ thresholdMs: 250 }),
],

Before, this comment claimed a cache hit "short-circuits before any downstream middleware (lints, budgets) fires" — behavior the framework does not have.

Decision

Comment-only PR (no runtime change): correct three doc comments that describe middleware-lifecycle behavior the framework does not have.

1. db.ts middleware-order comment — reworded to state what cache-first ordering actually buys (intercept precedence) and what a hit actually skips (the driver call and onRow, nothing else).
2. find-user-by-id-cached.ts observability note — dropped the claim that "telemetry is wired in front of the cache in db.ts"; no telemetry middleware exists anywhere in the repo. The note now states the real mechanism (afterExecute fires for every middleware on a hit, tagged source: 'middleware') and points at slowQueryWarning, the actual observer registered in db.ts.
3. middleware-cache package doc — the package's own hook documentation carried the same error ("the runtime skips beforeExecute, runDriver, and onRow") and is the likely origin of the stale example wording. Fixed the beforeExecute claim.

Reviewer notes

• The third file (packages/3-extensions/middleware-cache/src/cache-middleware.ts) is outside the examples scope the validation flagged, but it carries the identical false claim and likely seeded it. One-sentence doc fix; happy to split it out if you prefer this PR examples-only.
• This PR targets the Add slow-query warning custom middleware example to prisma-next-demo #912 branch, so the diff shown is exactly the three-file comment fix. When Add slow-query warning custom middleware example to prisma-next-demo #912 merges, GitHub retargets this to main automatically (or I can rebase).
• I audited the other "short-circuit" mentions across examples/ and the cache package: they all use the term in the accurate sense (the driver is skipped) and stand unchanged.
• No Linear ticket exists for this fix (it comes from the docs-validation GitHub issue), so the title follows the plain style of Add slow-query warning custom middleware example to prisma-next-demo #912/docs: update Supabase runtime README #913 rather than the TML-NNNN: convention; left unchecked in the checklist below.
• The pre-commit lint-deps hook could not run locally (dependency-cruiser requires Node ≥ 24; the local shell had 23.7), so the commit bypassed it. The diff is comment-only with imports untouched; CI runs the authoritative check.

How the lifecycle actually works

The corrected wording follows the execution order that run-with-middleware.ts documents as canonical:

1. beforeExecute runs first, for every middleware. Family runtimes call runBeforeExecuteChain between AST → plan lowering and parameter encoding (sql-runtime.ts, before-execute-chain.ts), so lints and budgets vet every execution before any cache lookup happens.
2. intercept is consulted afterwards, in registration order; the first non-undefined result wins. That precedence is the actual reason to register the cache first.
3. A hit skips the driver call and per-row onRow hooks — nothing else. afterExecute still fires for every middleware with source: 'middleware', which is how observers such as slow-query-warning.ts see cached reads.

What changed & evidence

• examples/prisma-next-demo/src/prisma/db.ts — middleware-order comment now describes intercept precedence and what a hit skips. The hit path is pinned by repositories.integration.test.ts (second cached call never reaches driver.execute).
• examples/prisma-next-demo/src/orm-client/find-user-by-id-cached.ts — observability bullet now references slowQueryWarning instead of a nonexistent telemetry middleware. The afterExecute-fires-on-hit behavior is pinned by cache-middleware.test.ts.
• packages/3-extensions/middleware-cache/src/cache-middleware.ts — hook doc no longer claims beforeExecute is skipped on a hit.

Testing performed

• pnpm --filter prisma-next-demo --filter @prisma-next/middleware-cache typecheck — passes. Comment-only change with no behavioural delta, so no test updates.

Skill update

n/a — doc comments only; no user-facing surface (CLI, public API, config, error codes) changed.

Alternatives considered

• Make the code match the comment instead (have a cache hit actually suppress lints/budgets): rejected — running beforeExecute before parameter encoding is deliberate, so middleware that mutates ParamRef values (e.g. bulk-encrypt) stays visible to encode; run-with-middleware.ts documents this lifecycle as canonical.
• Drop the telemetry sentence entirely rather than rewording: rejected — the underlying fact (afterExecute still fires on hits, tagged source: 'middleware') is the useful teaching point, and Add slow-query warning custom middleware example to prisma-next-demo #912's slowQueryWarning finally gives it a real referent.
• Restrict the PR to examples/ and leave the package doc stale: rejected — it is the same false claim and the likely origin; fixing it here keeps one logical concern in one review.

Checklist

• All commits are signed off (git commit -s) per the DCO.
• I read CONTRIBUTING.md and the change is scoped to one logical concern.
• Tests are updated — n/a: doc-comment-only, no behavioural delta.
• PR title in TML-NNNN: form — no Linear ticket exists for this fix; plain title per the precedent of Add slow-query warning custom middleware example to prisma-next-demo #912/docs: update Supabase runtime README #913 (see reviewer notes).
• The Skill update section above is filled in (n/a — doc comments only).

Summary by CodeRabbit

• Documentation
  • Clarified middleware lifecycle behavior for cache hits, including which callbacks run and which execution steps are skipped.
  • Updated examples to accurately describe cache-hit observability and middleware ordering.
  • Added upgrade-guide notes identifying these as documentation-only corrections with no user action required.